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system  was  checked  for  conformance  with  applicable  sections  of  3560.1  and 
1679.   In  addition,  the  documentation  system  was  compared  with  applicable 
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ance.  It  was  found  that  6.0/. 20  does  not  include  coverage  of  many  of  the 
applicable  sections  of  the  three  documents. 


SUMMARY 

Trident  CCSMA  requested  the  Naval  Postgraduate  School  to  evaluate 
the  "Maintainability  Enhancement  for  TCP/TSP  Revision  6.0  Update  .20," 
referred  to  as  6.0/. 20.   The  approach  for  accomplishing  this  task  was  to 
compare  6.0/. 20  for  compliance  or  conformity  with  applicable  sections  of 
SECNAVINST  3560.1,  FIPS  PUB  38,  AND  MIL-STD  1679.   In  addition,  a 
sample  of  6.0/. 20,  Volume  2,  was  examined  in  some  detail  for  its  useful- 
ness as  a  software  maintenance  tool  in  terms  of  consistency,  completeness, 
under standability ,  and  absence  of  errors.   Many  suggestions  for  improve- 
ment have  been  made . 

Our  conclusions  are  that  6.0/. 20: 

Does  enhance  maintainability.   However,  we  believe  listings 
alone,  even  if  they  are  structured,  are  inadequate  for  mainten- 
ance purposes. 

Does  not  include  coverage  of  significant  applicable  items  called 
for  in  3560.1,  FIPS  PUB  38,  and  1679. 

Appears  to  be  incomplete  and  to  contain  a  moderate  amount  of 
inconsistencies,  ambiguities,  and  errors. 

Could  provide  an  excellent  software  maintenance  tool  if  its 
quality  were  improved  in  accordance  with  the  suggestions  made 
in  this  report. 
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I.   INTRODUCTION 

A.  Purpose 

Trident  CCSMA  has  requested  the  Naval  Postgraduate  School  (NPS)  to 
evaluate  the  "Maintainability  Enhancement  for  TCP/TSP  Revision  6.0 
Update  .20"  documents,  subsequently  referred  to  as  6.0/. 20,  with 
respect  to  its  usability  for  maintaining  Trident  Command  and  Control 
System  software. 

B.  Approach 

It  is  understood  that  one  of  the  governing  documents  for  the  pro- 
duction and  use  of  Trident  software  is  "Department  of  the  Navy  Tactical 
Digital  Systems  Documentation  Standards,"  SECNAVINST  3560.1,  3  August 
1974.   Therefore,  it  was  deemed  appropriate  to  use  this  standard  as 
one  means  of  evaluating  the  subject  documents.   It  was  felt  that,  as  a 
minimum,  documentation  used  on  the  Trident  project  should  meet  the 
applicable  sections  of  this  standard.   However,  recognizing  that  this 
standard  was  issued  many  years  ago  and  that  the  field  of  software 
engineering  has  evolved  in  the  interim,  additional  criteria  which 
reflect  more  modern  software  design  and  maintenance  techniques  were 
used  in  the  evaluation. 

The  part  of  3560.1  which  appears  to  be  most  applicable  to  maintenance 
is  the  Program  Description  Document,  pages  2-137  to  2-152.   As  stated 
in  this  document,  its  purpose,  in  part,  is  the  following:  "As  a  detailed 
compendium  of  the  subprogram  structure,  the  Program  Description  document 


will  serve  as  the  essential  instrument  for  subsequent  use  by  operational, 
maintenance ,  and  contractor  personnel  diagnosing  troubles,  making 
adaption  changes,  designing  and  implementing  modifications  to  the 
system,  and  introducing  or  adding  new  subprogram  functions  to  the 
completed  program"  (underlining  added  by  the  author) . 

Another  means  of  evaluation  was  with  respect  to  the  publication 
"Guidelines  for  Documentation  of  Computer  Programs  and  Automated  Data 
Systems,"  National  Bureau  of  Standards,  Federal  Information  Processing 
Standards  Publication  38  (FIPS  PUB  38),  February  15,  1976.   As  stated 
in  FIPS  PUB  38,  its  purpose  is  the  following:   "These  guidelines  pro- 
vide a  basis  for  determining  the  content  and  extent  of  documentation  for 
computer  programs  and  automated  data  systems.   Software  development 
phases  and  related  document  types  are  identified,  several  examples  of 
documentation  options  are  given,  and  content  guidelines  for  ten  document 
types  are  provided."   Although,  officially,  this  guideline   is  not 
applicable  to  Trident  software  because  it  was  written  to  apply  to  ADP 
systems  under  the  provisions  of  Public  Law  89-306  (Brooks  Bill)  ,  which 
excluded  embedded  computer  systems,  it  is  of  technical  interest  because 
it  is  one  of  the  few  Federal  Government  software  guidelines  which 
covers  program  maintenance. 

As  stated  in  FIPS  PUB  38,  "The  purpose  of  the  Program  Maintenance 
Manual  is  to  provide  the  maintenance  programmer  with  the  information 
necessary  to  understand  the  programs,  their  operating  environment, 
and  their  maintenance  procedures."   The  Program  Maintenance  Manual 
is  described  on  pages  45-47  of  FIPS  PUB  38. 

It  was  also  considered  important  to  examine  6.0/. 20  with  respect 
to  the  applicable  sections  of  MIL-STD  1679  (Navy),  1  December  1978, 
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the  Navy's  Military  Standard  for  Weapon  System  Software  Development.   The 
applicable  section  of  1679  is  primarily  5.11  Configuration  Management, 
pages  23-24. 

C.   Scope 

In  order  to  ensure  good  software  maintainability,  it  is  necessary 
to  use  sound  programming  methodology  and  procedures,  as  well  as  pro- 
vide good  documentation.   It  is  difficult  to  evaluate  the  quality  of 
documentation  and  not  also  consider  the  quality  of  the  product  that 
has  been  documented,  because  good  documentation  of  non-structured  pro- 
grams which  contain  machine  language  code,  although  of  some  benefit, 
will  not  result  in  good  software  maintainability,  nor  will  good  docu- 
mentation of  highly  patched  programs  allow  software  to  be  easily 
maintained.   In  other  words,  if  programs  are  inherently  difficult  to 
change  and  understand  and  may  not  have  been  designed  with  maintain- 
ability in  mind,  documentation  may  only  make  a  marginal  contribution 
to  the  improvement  of  maintainability.   Thus,  this  project  poses  a 
dilemma  because  we  have  been  asked  to  review  and  evaluate  documentation 
for  programs  which  are  non-structured,  contain  significant  amounts  of 
machine  language  code,  and  are  highly  patched.   It  is  understandable 
that  this  is  the  case,  since  the  programs  were  designed  prior  to  the 
availability  of  a  mature  structured  programming  methodology  and  high 
level  languages  for  tactical  system  software  development.   In  addition, 
although  machine  language  patching  is  generally  considered  to  be  un- 
desirable, for  certain  administrative  and  contractual  reasons  it  is  a 
prevalent  practice  in  Navy  embedded  computer  software  development.   The 
argument  can  be  made. that,  because  of  these  practices,  good  documentation  is 


even  more  important  in  this  environment  than  it  would  be  in  those 
situations  where  the  use  of  structured  programming  and  high  level 
languages  provide  a  degree  of  self -documentation.   Accordingly,  the 
scope  of  this  paper  will  be  limited  to  evaluating  the  adequacy  of 
6.0/. 20  for  maintaining  the  TCP/TSP  software,  ignoring  what  is  per- 
haps the  more  fundamental  maintenance  issue  of  the  adequacy  of  the 
underlying  software . 

A  major  assumption  of  this  study  which  affects  its  scope   is  that 
the  6.0/. 20  documentation  is  to  be  evaluated  independently  of  the 
program  listings.   It  is  noted  that  listings  are  not  included  in  the 
version  of  6.0/. 20  dated  29  September  1979,  although  these  were  included 
in  a  prior  version  (undated) .   Quoting  from  Volume   1  of  the  version 
dated  29  September  1979,  "The  primary  goal  is  to  improve  this  software's 
maintainability  by  making  the  programs  and  their  patches  understandable 
and  visible  in  a  single  simplified  form,"  (underlining  added  by  the 
author) .   The  implication  which  has  been  derived  based  on  the  above 
statement  and  the  fact  that  the  listings  are  not  included  in  the 
latest  version,  is  that  6.0/. 20  is  to  be  used  for  maintenance  pur- 
poses primarily  on  a  stand-alone  basis  with  listings  utilized  as  a 
secondary  source  of  information.   This  interpretation  is  critical 
with  respect  to  some  of  the  results  obtained  in  this  study,  because 
certain  deficiencies  in  6.0/. 20,  which  are  noted  later  in  this  report, 
regarding  such  items  as  data  design,  tables  and  indexes,  are  not 
addressed  by  6.0/. 20  but  are  covered  in  the  listings.   If  it  was  the 
intent  to  use  the  listings  with  6.0/. 20  in  a  coordinated  fashion,  it 
would  be  helpful  to  provide  a  detailed  cross-referencing  between  the 
two.   A  method  for  accomplishing  this  cross-referencing  is  suggested 
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in  a  later  section.   The  scope  of  this  report  is  limited  to  considering 
6.0/. 20  as  an  independent  tool  for  maintenance  which  does  not  rely  exten- 
sively on  the  use  of  program  listings.   However,  since  the  flowcharts 
are  based  on  the  program  logic,  as  expressed  in  the  listings,  it  was 
necessary  to  make  extensive  reference  to  the  listings  in  this  report 
in  order  to  understand  and  evaluate  5.0/. 20.   In  fact,  a  result  of  this 
analysis  was  the  conclusion  that  the  two  mediums  should  be  used  as  an 
integrated  documentation  package  and  not  in  isolation. 


II.   EVALUATION  OF  6.0/. 20 


A.   With  Respect  to  SECNAVINST  3560.1,  Program  Description  Document, 
Pages  2-137  to  2-152. 

The  following  3560.1  pages  and  sections  are  covered  by  6.0/. 20: 
Page       Section    Title 


2-141 
2-141 
2-142 


1. 
2. 

3. 


Scope 

Applicable  Documents 

Requirements 


2-142 
2-143 
2-148 
2-149 


3.1  Subprogram  Detailed  Description 

3.2  Subprogram  Flow  Diagrams 
3.6  Conditions  for  Initiation 
3.8  Interface  Description 


The  3560.1  pages  and  sections  which  apparently  are  not  covered  by 
6.0/. 20  are  identified  below.   It  is  possible  that  these  sections  are 
not  applicable  to  certain  volumes  of  6.0/. 20.   However,  the  named  missing 
sections  were  not  found  in  any  of  the  6.0/. 20  volumes  for  which  copies 
were  provided  to  NPS,  so  it  is  assumed  that  it  was  not  intended  to 
include  these  sections  in  6.0/. 20.   A  brief  description  of  the  intended 
contents  of  the  missing  sections  as  specified  by  3560.1  is  given: 


Page 
2-144 

2-144 


Section 


3.3 


3.3.1 


Title 


Contents 


Subprogram  Data  Design   General  summary  descrip- 
tion of  the  subprogram 
data  base. 

Tables  Detailed  description  of 

each  table  used  in  the 
subprogram  data  base : 

a.  Table  name. 

b.  Purpose  and  type. 

c.  Size  and  indexing 
procedure . 

d.  Structure  and  bit 
layout . 
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2-145 


3.3.2 


Variables 


Detailed  description  of 
each  variable  used  in 
the  subprogram  data 
base : 

a.  Variable  name. 

b.  Purpose. 

c.  Structure  and  bit 
layout. 


2-145 


3.3.3 


Flags 


Detailed  description  of 
each  flag  used  in  the 
subprogram  data  base: 

a.  Flag  name. 

b.  Purpose  and  status. 

c .  Structure  and  bit 
layout. 


2-145 


3.3.4 


Indexes 


Technical  description 
of  each  index  used  in 
the  subprogram  data 
base: 

a .  Index  name . 

b.  Purpose. 


2-146 


3.3.5    Common  Data  Base 
Reference 


Complete  list  of  all 
references  to  local 
and  common  data  base 
items  and  the  location 
of  each  reference. 


2-146 


3.4 


Input/Output  Formats 


Brief  description  and 
graphic  (sample)  repre- 
sentation of  each  input 
and  output  message , 
card  format,  tape  for- 
mat, etc.  processed  by 
the  subprogram. 


2-148 


3.7 


Subprogram  Limitations 


Summary  of  any  known  or 
anticipated  limitations 
of  the  subprogram. 


2-149 


4. 


Quality  Assurance 
Provisions 


Reference  to  all  appli- 
cable test  plans  and 
procedures  that  have 
been  used  for  verifica- 
tion of  the  subprogram. 
(6.0/. 20  should  reference 
the  Trident  Test  Speci- 
fication Requirements 
and  Test  Procedures 
which  are  described  in 
Refs.  1  and  2.) 
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NOTE:   It  was  not  possible  to  determine  whether  Section  3.5  Required  Sys- 
tem Library  Subroutines  was  covered  by  6.0/. 20  because  it  was  not  known 
whether  library  subroutines  were  used. 

B.   With  Respect  to  FTPS  PUB  38,  Program  Maintenance  Manual  ,  Pages  45-47 

The  following  Program  Maintenance  Manual  sections  are  covered  by  6.0/. 20 
Section  Title 

1_. General  Information 

1 . 1  Summary 

1.2  Environment 

1.3  References 

2  . Program  Descriptions 

2.1  Program  Identification 

2.1.1  Problem  and  Solution  Method 

2.1.2  Input  (description  of) 

2.1.3  Processing  (logic,  linkages,  error 

handling) 

2.1.4  Output  (description  of) 

2.1.5  Interfaces 
2.1.7                       Run  Description 

3. Operating  Environment 

3.2  Support  Software 

3.2.1  Operating  System 

3.2.2  Compiler,  Assembler 

The  Program  Maintenance  Manual  sections  which  apparently  are  not 
covered  by  6.0/. 20  are  identified  below.  The  caveats  that  were  stated 
relative  to  3560.1  also  apply  to  this  section. 
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Section 


Title 


Contents 


2.1.2 


Input 


2.1.3 

2.1.4 
2.1.6 

3.1 

3.3 


Processing 

Output 
Tables 

Hardware 

Data  Base 


Layout,  medium,  codes,  units  of 
measurement,  format,  range  of  values 
or  reference  to  a  data  element 
dictionary. 

Variables,  constants,  restrictions, 
switches,  flags. 

Layout,  medium. 

Identification,  content,  location, 
structure,  purpose. 

Equipment  required  for  operation  of 
system  and  for  each  program. 

Description  of  data  bases  used  or 
reference  to  a  data  element  dictionary 
(codes,  units  of  measurement,  format, 
range  of  values) . 


4. 


Maintenance  Procedures 


4.1 


Programming 
Conventions 


Identification  and  descriptions. 


4.2 


Verification 
Procedures 


Description  of  procedures  to  check 
the  performance  of  programs ,  in 
general  and  following  modification. 
Reference  to  test  data  and  testing 
procedures.   (6.0/. 20  should 
reference  the  Trident  Test  Specifi- 
cation Requirements  and  Test  Pro- 
cedures which  are  described  in 
Refs.  1  and  2) . 


4.3 


Error  Correction 
Procedures 


Description  of  error  conditions , 
sources  and  procedures  for  correc- 
tion.  (6.0/. 20  should  reference 
the  Trident  CCS  Problem  Reporting 
and  Modification  Systems  which  are 
described  in  Refs.  1  and  2.) 


4.4 


Special 

Maintenance 

Procedures 


Description  of  special  procedures 
which  change  with  time  or  conditions 
(e.g.,  change  of  parameters,  algo- 
rithms) . 


4.5 


Listings  and 
Flowcharts 


Information  about  how  to  obtain 
copies  of  listings  and  flowcharts 


13 


NOTE:   It  is  possible  that  Section  3.3  Data  Base  is  not  applicable  to 
any  of  the  programs  documented  by  6.0/. 20. 

C.   With  Respect  to  MIL-STD  1679  (Navy) ,  Configuration  Management, 
Pages  23-24 

The  following  configuration  management  sections  of  1679  are  covered 
by  6.0/. 20: 

Section      Title 

5  .11 Configuration  Management 

5.11a      Positive  identification  of  all  program  components 
5  .11.1 Configuration  Identification 

5.11.1.1  Baselines 

5.11.1.2  Documentation  Identification 
5.11.1.2a  Component 

b.  Purpose 

c.  Baseline 

d.  Serial,  edition  and  change  status 

The  sections  which  apparently  are  not  covered  by  6.0/. 20  are 

identified  below.   The  caveats  that  were  stated  relative  to  3560.1 

also  apply  to  this  section. 

Section      Title 

5.11b      Treatment  of  proposed  changes  to  components  under 
configuration  control. 

5.11c      Implementation  of  approved  changes  and  dissemination 
of  corrected  documentation  and  program  changes. 

5. lid      Recording  of  status  of  all  proposed  changes. 

5. lie      Verification  of  change  control,  identification  and 

status  account  of  documentation  and  program  materials . 
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5.11.2 


Configuration  Control 


5.11.2.1 


5.11.2.3 


5.11.3 


Software  Changes 


5.11.2.2    Documentation  Changes 


Software  Configuration 
Control  Boards 


Configuration  Status 
Accounting 


Procedures  for  formal 
control  of  all  docu- 
ments, program  materials 
and  support  library 
shall  be  established. 

Proposed  changes  to 
software  which  is 
under  configuration 
control  shall  be 
submitted  to  the  ap- 
propriate software 
configuration  control 
boards . 

Procedures  for  control- 
ling preparation  and 
dissemination  of  changes 
to  documentation  shall 
be  developed. 

Each  baseline  plus 
approved  changes  from 
those  baselines  shall 
be  under  the  formal 
control  of  a  respon- 
sible board. 

Procedures  to  enable 
the  generation  of 
periodic  status  reports 
on  all  components  under 
configuration  management 
shall  be  established. 


With  respect  to  the  above  sections,  6.0/. 20  should  reference  the 
Trident  CCS  Problem  Reporting  and  Modification  Systems  and  the  Configu- 
ration Management  System  which  are  described  in  Ref s .  1  and  2. 
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III.   OTHER  COMMENTS 

The  following  comments  pertain  to  6.0/. 20  Volume  2,  using  it  as 
an  example. 

A.  Functional  Description,  on  Pages  3-1  to  3-3 

1.  The  discussion  would  be  more  meaningful  if  it  were  keyed  to  the 
hierarchical  structure  diagrams  and  to  the  flowcharts .   For  example , 
definitions  and  descriptions  of  pertinent  interrupts  should  be  provided, 
including  important  symbolic  addresses  which  are  utilized.   This  informa- 
tion and  the  interrupt  numbers  should  be  related  to  the  diagrams. 

2.  Sub-headings  for  the  various  sections,  such  as  "Interrupt 
Handling,"  would  make  the  text  more  readable. 

3.  Some  typos  were  observed  which  affect  understandability .   For 
example,  the  fifth  line  in  the  second  paragraph  on  page  3-3. 

4.  Although  this  comment  does  not  concern  quality  of  documentation, 
it  was  noted  on  page  3-2  that  the  control  memory  test  for  all  zeros  and 
all  ones  should  be  preceded  by  setting  the  relevant  portions  of  main 
memory  to  non-zero  and  non-one  data,  respectively,  prior  to  the  transfer 
of  control  memory  to  main  memory. 

B.  Hierarchical  Structure  Diagrams 

1.   Hierarchical  structure  diagrams  and  flowchart  symbols  should 
be  defined  at  the  beginning  of  each  volume.   It  is  not  clear  that  these 
diagrams  strictly  adhere  to  ANSI  standards  (see  Reference  3) . 
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2 .  A  consistent  hierarchical  structure  box  numbering  system  should 
be  utilized  which  would  indicate  at  a  glance  two  important  pieces  of 
information:   the  function  (e.g.,  "Periodic  Entry")  to  which  the  routine 
belongs,  and  the  level  of  the  routine  within  the  function.   This  scheme 
is  shown  on  the  accompanying  hierarchical  structure  diagrams,  which  were 
reproduced  from  Volume  2  (pages  4-4  to  4-8) .   The  left  digit  is  function 
number,  the  middle  digit  is  level  number  and  the  right  digit  is  routine 
number  for  a  given  level  and  function.   Level  numbers  start  at  "1" 

and  increase  from  top  to  bottom;  routine  numbers  start  at  "1"  and 
increase  from  left  to  right.   These  numbers  should  be  referenced  to 
the  pertinent  flowcharts ,  as  shown  on  the  accompanying  diagrams  (pages 
4-9  to  4-12  of  Volume  2) .   As  a  means  of  tying  together  hierarchical 
structure  diagrams,  flowcharts  and  listings,  the  identification  numbers 
could  be  appended  to  the  listings  as  shown  on  the  reproduced  CMS-2 
Assembler  listing  (page  6  of  listing) ,  which  is  attached.   Two  columns 
are  utilized:   one  is  the  "At"  column  corresponding  to  lines  with  labels; 
the  other  is  the  "To"  column  corresponding  to  lines  with  transfer  of 
control.   Perhaps  these  identifiers  could  be  punched  and  printed  in 
formatted  columns  as  part  of  the  "Comments"  field.   A  further  help  would 
be  to  sort  source  statements  by  the  "At"  column  and  to  indent  based  on 
the  middle  digit.   This  would  provided  a  structured  listing  of  an  entire 
function  in  contiguous  locations. 

3.  Although  it  is  not  a  fault  of  the  flowcharting  process,  it 
was  observed  that  there  is  a  similarity  of  labels  (e.g.,  CTPRE  and 
CTPER) .   This  could  lead  to  error  in  software  maintenance . 
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C.  Flowcharts 

1.  The  entry  to  a  flowchart  page  should  be  annotated  with  the  flow- 
chart page  numbers  which  are  associated  with  the  source (s)  of  the  trans- 
fer of  control  and  the  exit(s)  from  a  flowchart  page  should  indicate 

the  page  number (s)  which  are  associated  with  the  destination (s)  of  the 
transfer  of  control.   This  is  shown  on  the  attached  pages  4-9  to  4-12 
of  Volume  2 . 

2.  There  is  no  loop  back  to  CTPERl  on  page  4-9  of  the  flowcharts, 
as  indicated  by  the  JBNZ  instruction  at  line  223  on  page  6  of  the 
listing.   Instead  the  box  at  the  bottom  of  page  4-9  reads:   "Repeat  Data 
Pattern  Test  Using  'TWC  Control  Word."    Similarly  there  is  no  loop 
back  to  CTPER2  on  page  4-10  nor  loop  back  to  CTPER3  on  page  4-11,  as 
shown  by  line  230  and  238,  respectively,  on  the  listing.   This  method 

of  presentation  seems  to  mask  an  important  characteristic  of  the 
program  logic. 

3.  There  seem  to  be  discrepancies  between  flowcharts  and  listings. 
For  example,  the  second  box  from  the  bottom  of  page  4-11  figure  4.3 
refers  to  IWC.   Page  6,  lines  243  and  244  refer  to  ICW.   The  box  in 
the  flowchart  also  refers  to  "Set  Up  Class  IV,"  while  line  243  on  the 
listing  refers  to  Class  II. 

D.  Interpretation  of  Hierarchical  Structure  Diagrams 

1.   Using  Volume  2  as  an  example,  it  appears  that  the  hierarchical 
structure  diagrams  are  not  totally  accurate  in  portraying  program  logic . 
For  example ,  the  following  discrepancies  were  noted  between  hierarchical 
structure  and  the  listings: 
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a.   With  respect  to  page  4-5,  figure  4.2,  CTPER  is  shown 
superior  to  all  other  routines  on  this  chart,  yet  an  analysis  of  the 
listing  reveals  that  CTPER  only  happens  to  be  the  first  label  in  this 
series  of  code  and  its  only  paths  to  other  labels  are  to  CTPERl  and 
CTPERROR.    The  latter  reference  brings  to  light  another  discrepancy. 
CTPER  does  have  a  conditional  branch  to  CTPERROR  in  the  listing  (line 
219),  but  according  to  figure  4.2,  there  is  no  path  between  these 
routines.   Wtih  respect  to  figure  4.2,  the  listings  indicate  the  follow- 
ing access  paths  among  routines : 

-  CTPER  accesses  CTPERl  and  CTPERROR. 

-  CTPERl  accesses  CTPER2  and  CTPERROR. 

-  CTPER2  accesses  CTPER3  and  CTPERROR. 

-  CTPER3  accesses  CTRTN  and  CTPERROR. 

Thus,  a  more  accurate  picture  of  this  logic  is  shown  in  the  diagram 
labeled  "Revised  Figure  4.2  CT  Hierarchical  Structure  (2  of  5)."   It 
should  be  noted  that  in  this  diagram  the  horizontal  lines  indicate 
paths  between  adjacent  code  segments  that  are  in  the  same  module  and 
vertical  lines  indicate  paths  involving  transfer  of  control.   Also, 
the  arrows,  from  left  to  right  and  from  top  to  bottom,  indicate  the 
general  direction  of  control  flow.   In  large  measure  the  "routines" 
which  have  been  shown  as  hierarchical   structures  boxes  in  Volume  2 
are  simply  labels  in  a  segment  of  code.   This  has  been  pointed  out  in 
Volume  2  on  page  4-3.   The  difficulty  in  constructing  the  hierarchical 
structure  from  program  listings  is  that  by  definition,  the  diagrams 
are  supposed  to  indicate  hierarchy,  i.e.,  superior-subordinate  relation- 
ships, and  programs  designed  using  a  top-down  approach.   Since  the 


19 


programs  were  not  written  this  way ,  the  imposition  of  a  hierarchical 
structure  on  a  coding  format  that  is  inherently  non— structured  will 
lead  to  incompatibilities  between  diagrams  and  listings,  unless  great 
care  is  exercised  in  performing  the  translation. 

b.   Pages  4-7  and  4-8,  figure  4.2,  show  CTKLAS2  as  having  access  to 
CTKLASY.   The  listing  indicates  that  this  actually  occurs  via  CTKLIPI 
(lines  314  and  342),  which  is  not  listed  as  a  routine  in  figure  4.1, 
page  4-2  of  volume  2.   CTKLIPI  also  has  a  path  to  CTARITH  via  CTKL2XIT 
at  line  349.   Page  4-8  also  shows  no  path  between  CTKAS2I  and  CTKLASY*. 
However,  the  listing  shows  this  path  to  exist.   This  condition  was 
verified  by  consulting  the  CMS-2  Assembler  List  Cross  Reference  Table. 
One  of  these  references  to  CTKLASY  occurs  from  the  same  routine. 

-  Pages  4-7  and  4-8  show  no  path  between  CTKLAS2  and  CTKLAS2Z. 
However,  line  335  on  the  listing  shows  that  this  label  is  contained 
within  routine  CTKLAS2 . 

-  Page  4-8  shows  no  path  between  CTKLASY  and  CTKLAS2J.   A 
check  of  the  List  Cross  Reference  Table  revealed  that  this  path  does 
exist;  this  reference  to  CTKLAS2J  occurs  at  line  430.   However,  this 
path  is  used  only  when  a  4  stop  condition  does  not  exist. 

Taking  the  above  difference  into  account ,  page  4-8  has  been 
redrawn  and  is  labeled  as  "Revised  Figure  4.2  CT  Hierarchical  Structure 

(5  of  5)."   Again,  the  procedure  was  to  use  horizontal  arrows  (going 
into  side  of  box)  to  indicate  adjacent  code  segment  relationships 

(e.g.,  between  CTKLAS2  and  CTKLAS2Z  and  between  CTKLAS2I  and  CTKLAS2J) 
and  vertical  arrows  (going  into  top  of  box)  to  show  transfer  of  control. 


*At  least  it  is  not  unambiguous  as  to  whether  there  is  a  path  between 
CTKLAS2  and  CTKLASY  or  between  CTKLAS2I  adn  CTKLASY,  or  both. 
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Note:   The  revised  hierarchical  structure  diagrams  would 
obviously  have  different  numbers  for  some  boxes  than  those  used  in 
Section  B.2.   The  latter  was  based  on  the  given  hierarchical  structure 
diagrams  as  shown  in  Volume  2 . 

c.   It  was  not  clear  in  what  sense  lines  with  arrows  and  those 
without  arrows  were  used  in  the  hierarchical  structure  diagrams  of 
Volume  2.   If  the  use  of  arrows  was  to  show  transfer  of  control  and  the 
absence  of  arrows  to  tie  together  routines  of  the  same  module,  the 
method  would  be  inconsistent  because  there  are  no  arrows  on  the  lines 
which  connect  CTKLAS2  to  CTKLAS2 (A-I)  in  figure  4.2  of  Volume  2. 

E.  Inter-Module  Message  Tables 

These  tables,  such  as  the  one  on  page  4-34,  figure  4.4,  Volume  2, 
should  indicate  the  page  number  of  the  flowchart  of  the  referenced 
procedure  (routine) . 

F.  Configurations 

The  hardware  and  configuration  to  which  6.0/. 20  applies  should  be 
defined  in  each  volume . 

G.  Patch  Listings 

Patch  listings  in  Volume  1  should  have  column  headings . 

H.   Audit  Comments 


Although  we  do  not  agree  with  the  comment  on  page  A-l,  Volume  2 
that,  "...   the  module  is  readily  understandable  even  though  it  is 
non-modular,"  we  do  feel  that  this  is  a  valuable  part  of  maintenance 
documentation.   Perhaps  this  section  could  be  expanded. 
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From  Page  4-10 
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